<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Example Class Usage Notes</title>
  <link rel="stylesheet" type="text/css" href="../mbgstyle.css" />
</head>
<body>
<h1>Example Class Usage Notes</h1>
<p>The example class specifies how to build a dynamic where clause.  Each non-BLOB column in the
table can optionally be included in the where clause.  Examples are the best way
to demonstrate the usage of this class.</p>
<p>The example class can be used to generate a virtually
unlimited where clauses.</p>
<p>The example classes contain
an inner static class called <code>Criteria</code>
that holds a list of conditions that will be <code>anded</code> together in the where clause.  The
example class holds a list of <code>Criteria</code> objects and all the clauses
from the inner classes will be <code>ored</code> together.  Using different sets of
<code>Criteria</code> classes allows you to generate virtually unlimited
types of where clauses.</p>
<p><code>Criteria</code> objects can be created with the either the <code>createCriteria</code> method
or the <code>or</code> method
in the example class.  When the first <code>Criteria</code> object is created with the
<code>createCriteria</code> method it is automatically
added to the list of <code>Criteria</code> objects - this makes it easy to write
a simple where clause if you don't need to <code>or</code> several other clauses together.
When using the <code>or</code> method, the <code>Criteria</code> class is added to the
list in all instances.</p>

<p><b>Important</b> We recommend that
you only use the <code>or</code> method for creating <code>Criteria</code> classes.  We
believe that this method makes for more readable code.</p>

<h2>Simple Queries</h2>
<p>This example shows how to generate a simple WHERE clause using the generated
example class:</p>

<pre>
  TestTableExample example = new TestTableExample();

  example.createCriteria().andField1EqualTo(5);
</pre>

<p>Alternatively, the following syntax also works:</p>
<pre>
  TestTableExample example = new TestTableExample();

  example.or().andField1EqualTo(5);
</pre>

<p>In either above example, the dynamically generated where clause will effectively be:</p>
<pre>
  where field1 = 5
</pre>

<h2>Complex Queries</h2>
<p>The next example shows how to generate a complex WHERE clause using the generated
example class (using JSE 5.0 parameterized types):</p>
<pre>
  TestTableExample example = new TestTableExample();

  example.or()
    .andField1EqualTo(5)
    .andField2IsNull();

  example.or()
    .andField3NotEqualTo(9)
    .andField4IsNotNull();

  List&lt;Integer&gt; field5Values = new ArrayList&lt;Integer&gt;();
  field5Values.add(8);
  field5Values.add(11);
  field5Values.add(14);
  field5Values.add(22);

  example.or()
    .andField5In(field5Values);

  example.or()
    .andField6Between(3, 7);

</pre>
<p>In the above example, the dynamically generated where clause will effectively be:</p>
<pre>
  where (field1 = 5 and field2 is null)
     or (field3 &lt;&gt; 9 and field4 is not null)
     or (field5 in (8, 11, 14, 22))
     or (field6 between 3 and 7)
</pre>
<p>Returned records will meet these criteria.</p>

<h2>Distinct Queries</h2>
<p>You can force queries to be DISTINCT by calling the <code>setDistinct(true)</code>
method on any example class.</p>

<h2>Criteria Classes</h2>
<p>The <code>Criteria</code> inner class includes <code>andXXX</code> methods for each field,
and each standard SQL predicate including:</p>
<ul>
  <li>IS NULL - meaning the related column must be NULL</li>
  <li>IS NOT NULL - meaning the related column must not be NULL</li>
  <li>= (equal) - meaning the related column must be equal to the value passed in on the method call</li>
  <li>&lt;&gt; (not equal) - meaning the related column must not be equal to the value passed in on the method call</li>
  <li>&gt; (greater than) - meaning the related column must be greater than the value passed in on the method call</li>
  <li>&gt;= (greater than or equal) - meaning the related column must be greater than or equal to the value passed in on the method call</li>
  <li>&lt; (less than) - meaning the related column must be less than the value passed in on the method call</li>
  <li>&lt;= (less than or equal) - meaning the related column must be less than or equal to the value passed in on the method call</li>
  <li>LIKE - meaning the related column must be "like" the value passed in on the method call.
    The code does not add the required '%', you must set that value yourself in the value you pass
    in on the method call.
  </li>
  <li>NOT LIKE - meaning the related column must be "not like" the value passed in on the method call.
    The code does not add the required '%', you must set that value yourself in the value you pass
    in on the method call.
  </li>
  <li>BETWEEN - meaning the related column must be "between" the two values passed in on
      the method call.</li>
  <li>NOT BETWEEN - meaning the related column must be "not between" the two values passed in on
      the method call.</li>
  <li>IN - meaning the related column must be one of the list of values passed in on
      the method call.</li>
  <li>NOT IN - meaning the related column must not be one of the list of values passed in on
      the method call.</li>
</ul>


</body>
</html>
